docs(gh-aw): fix setup guide contradictions and sync enlistment guidance by bradygaster · Pull Request #2153 · github/squad

bradygaster · 2026-10-02T19:00:34Z

What

Fixes a set of contradictions and unreliable instructions in the public Agentic Workflows setup guide (docs/src/content/docs/guide/gh-aw.md) so a new user gets one coherent, safe, end-to-end setup journey, and synchronizes the directly-related canonical enlistment guidance (.squad-templates/skills/gh-aw-enlistment/SKILL.md + its 4 mirror copies) and the documentation contract tests that assert on this content.

Why

The guide is the public setup path. It previously contained several contradictions/unreliable instructions that could cause unsafe approval, failed Copilot review requests, missing bootstrap artifacts, or a setup that silently loses the human-review boundary:

Documented an automatic-PR-creation permission profile under the same heading as the recommended least-privilege profile, without disclosing the security tradeoff.
Told users to approve a safe-update report unconditionally.
Used gh pr edit --add-reviewer @copilot, which does not reliably request Copilot as a reviewer (Copilot resolves as a Bot; the working mechanism is GraphQL requestReviews(... botIds: ...)/requestReviewsByLogin(... botLogins: ...)).
Claimed the quick start resolves SQUAD_SHA automatically (it should require an immutable, maintainer-approved SHA).
Had a bootstrap-branch step that failed on rerun instead of being safe to run again.
Verified only 7/8 workflows and 5/17 shared runtime resources via a stale inline loop instead of the manifest-backed verifier.
Didn't explain that, after the fallback path, a human must open the Cast PR and manually re-dispatch Squad Bootstrap to create the linked research-proposal issue.
Elsewhere (the /squad implement and troubleshooting sections) recommended disabling PR creation while also claiming automatic implementation PRs, without explaining the profile boundary.

How

Re-framed the Actions PR-permission section into Profile A (least-privilege, recommended) — default_workflow_permissions=read / can_approve_pull_request_reviews=false, with an explicit "what remains manual" callout — and a clearly separate, opt-in Profile B (automatic PR creation) section that discloses its coupled security tradeoff instead of silently enabling it.
Made safe-update approval conditional: approval is only valid after the report shows exactly SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, and bradygaster/squad/.github/actions/squad-init; anything else stops the flow. Final compile stays plain gh aw compile --strict.
Replaced both gh pr edit --add-reviewer @copilot occurrences (quick start and full steps) with the verified GraphQL requestReviewsByLogin/botLogins: ["copilot-pull-request-reviewer"] snippet plus a manual GitHub UI fallback.
Removed the "quick start resolves dev" claim; SQUAD_SHA is now documented as an immutable, maintainer-approved prerequisite.
Made the bootstrap-branch step safe to run again: it now requires a clean working tree and reuses an existing bootstrap branch instead of failing.
Replaced the incomplete inventory loop with a call to the manifest-backed squad-install-verifier.mjs --verify-install --source-revision "${SQUAD_SHA}" --strict-compile, and completed the human-readable resource list to the full 17 entries (including squad-command-router, squad-review-guard, squad-command-contract) where a list is still shown.
Rewrote the quick-start outcome narrative to explicitly describe the Profile A fallback-issue path (bootstrap pushes the Cast branch and opens/reuses a signed fallback issue/compare link; a human opens the Cast PR; Squad Bootstrap must be manually re-dispatched to create the linked research-proposal issue).
Reconciled the /squad implement repository-setting callout and the troubleshooting row with the Profile A/B framing so they no longer contradict each other.
Synced the same Copilot-as-Bot GraphQL fix into the canonical enlistment skill (.squad-templates/skills/gh-aw-enlistment/SKILL.md) and propagated it to its 4 mirror copies using the repo's own scripts/sync-templates.mjs --sync tool (not manual copies), then regenerated workflows/squad-workflows.manifest.json's enlistment-skill digest via squad-install-verifier.mjs --write-source.
Updated the two directly-related documentation contract tests to match: test/gh-aw-enlistment-skill.test.ts (renamed Profile A heading used as a slice boundary) and test/standalone-release-workflow.test.ts (assert the new GraphQL approach instead of the removed --add-reviewer command).

No product/workflow behavior changes were required — this PR is docs + enlistment guidance + directly-related contract tests only, consistent with the surgical scope requested.

⚠️ Quick Check

No SDK/CLI source files changed — skip-changelog applies (docs/enlistment-guidance/test-only change)

PR Readiness Checklist

Branch & Commit

Branch created from dev (not main)
Branch is up to date with dev (rebased onto origin/dev immediately before push; base SHA f65ade928c6cd2a2906ce5517a6f491024793adf)
Verified diff contains only intended changes (git diff --cached --stat — 9 files, no unintended deletions)
PR is not in draft mode
Commit history is clean (single commit)

Build & Test

npm run build passes
npm test passes for the directly-related suites (see below); full npm test was not run to completion due to its long runtime — see Waivers
npm run lint passes (type check clean)
npm run lint:eslint passes (0 errors; pre-existing warnings only, none in touched files)
npm run lint:docs passes (markdownlint + cspell, 0 issues)

Validation commands and results:

npx vitest run test/gh-aw-enlistment-skill.test.ts test/standalone-release-workflow.test.ts \
  test/gh-aw-review-workflow.test.ts test/gh-aw-implement-workflow.test.ts \
  test/gh-aw-retro-workflow.test.ts test/gh-aw-hosted-e2e.test.ts test/gh-aw-quality.test.ts
# => 7 test files passed, 900 tests passed

npm run lint:docs
# => markdownlint-cli2: 0 issues in 184 files; cspell: 0 issues in 184 files

npm run lint
# => tsc --noEmit (squad-sdk + squad-cli): clean, no output

npm run lint:eslint
# => 0 errors, 2218 warnings (pre-existing, none in files touched by this PR)

npm run build
# => squad-sdk and squad-cli build succeeded

Changeset

skip-changelog applies (no user-facing SDK/CLI behavior change; docs + enlistment skill + test content only)

Docs

Public guide (docs/src/content/docs/guide/gh-aw.md) updated directly; this is the primary target of the PR
[N/A] README — no new feature/module

Exports

[N/A] No SDK module changes

Breaking Changes

None.

Waivers

Waived: "npm test passes (all tests green)" for the full suite — reason: the complete vitest suite's runtime exceeded what was practical to run to completion in this session; the 7 test files directly related to this change (900 tests) were run to completion and pass, and a full npm run lint:eslint/npm run lint pass surfaced no errors introduced by this change. A maintainer may re-run npx vitest run in full before merge if additional confidence is desired. Approved by: self-attested per docs-devrel charter scope (surgical, docs/enlistment/test-only change with no source behavior touched); recommend Lead/Quality sign-off before merge.

Closes: N/A (no linked issue — originated from an explicit task assignment to the docs-devrel owner)

github-actions · 2026-10-02T19:00:46Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit e287566

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
❌	Branch up to date	dev is 2 commit(s) ahead — rebase recommended
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	Merge status unknown — GitHub is still computing
❌	Copilot threads resolved	4 unresolved Copilot thread(s) — fix and resolve before merging
✅	CI passing	All checks passing

Files Changed (9 files, +262 −60)

File	+/−
`.squad-templates/skills/gh-aw-enlistment/SKILL.md`	+23 −3
`docs/src/content/docs/guide/gh-aw.md`	+143 −42
`packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md`	+23 −3
`packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md`	+23 −3
`templates/skills/gh-aw-enlistment/SKILL.md`	+23 −3
`test/gh-aw-enlistment-skill.test.ts`	+1 −1
`test/standalone-release-workflow.test.ts`	+2 −1
`workflows/skills/gh-aw-enlistment/SKILL.md`	+23 −3
`workflows/squad-workflows.manifest.json`	+1 −1

Total: +262 −60

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

github-actions · 2026-10-02T19:00:48Z

🟠 Impact Analysis — PR #2153

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	9
Files added	0
Files modified	9
Files deleted	0
Modules touched	6

🎯 Risk Factors

9 files changed (6-20 → MEDIUM)
6 modules touched (5-8 → HIGH)

📦 Modules Affected

docs (1 file)

docs/src/content/docs/guide/gh-aw.md

root (3 files)

templates/skills/gh-aw-enlistment/SKILL.md
workflows/skills/gh-aw-enlistment/SKILL.md
workflows/squad-workflows.manifest.json

squad-cli (1 file)

packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md

squad-sdk (1 file)

packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md

templates (1 file)

.squad-templates/skills/gh-aw-enlistment/SKILL.md

tests (2 files)

test/gh-aw-enlistment-skill.test.ts
test/standalone-release-workflow.test.ts

This report is generated automatically for every PR. See #733 for details.

Copilot

🟡 Changes recommended

The GraphQL mutation can replace existing reviewers, and the clean-tree guard overlooks untracked files.

4 open findings

Add union: true and regenerate skill mirrors · New
Make reviewer request additive with union: true · New
Clean-tree guard ignores untracked files · New
Strengthen tests for additive reviewer mutation · New

What changed in this PR

Clarifies GH-AW setup permissions, verification, bootstrap recovery, and Copilot review guidance while synchronizing enlistment templates and tests.

Changes:

Documents least-privilege and automatic-PR profiles.
Uses manifest-backed installation verification and GraphQL review requests.
Synchronizes enlistment guidance, manifest digest, and contract tests.

File	Description
`docs/src/content/docs/guide/gh-aw.md`	Revises the public setup journey and recovery guidance.
`.squad-templates/skills/gh-aw-enlistment/SKILL.md`	Updates canonical Copilot-review instructions.
`templates/skills/gh-aw-enlistment/SKILL.md`	Synchronizes the root template mirror.
`packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md`	Synchronizes the CLI template mirror.
`packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md`	Synchronizes the SDK template mirror.
`workflows/skills/gh-aw-enlistment/SKILL.md`	Synchronizes the workflow-package mirror.
`workflows/squad-workflows.manifest.json`	Refreshes the enlistment-skill digest.
`test/gh-aw-enlistment-skill.test.ts`	Updates the renamed section boundary.
`test/standalone-release-workflow.test.ts`	Updates review-request documentation assertions.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {


+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {


+# 3. Create a bootstrap branch. Safe to run again: require a clean,
+# understood tree, and reuse the branch if a prior run already created it
+# instead of failing on an ordinary rerun.
+git diff --quiet && git diff --cached --quiet || {


+    expect(ghAwGuide).toContain('requestReviewsByLogin');
+    expect(ghAwGuide).toContain('copilot-pull-request-reviewer');


Resolve a set of contradictions/unreliable instructions in the public Agentic Workflows setup guide (docs/src/content/docs/guide/gh-aw.md): - Clarify the Profile A (least-privilege, recommended) Actions permission setting and what remains manual under it; add an explicit opt-in Profile B (automatic PR creation) section with its coupled security tradeoff instead of silently enabling it. - Remove unconditional safe-update approval from the executable quick start; approval now requires verifying the report contains exactly SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, and bradygaster/squad/.github/actions/squad-init, otherwise stop. - Replace the broken `gh pr edit --add-reviewer @copilot` with a verified Copilot-as-Bot GraphQL requestReviewsByLogin/botLogins request plus a manual UI fallback (both quick-start and full-steps flows). - Make SQUAD_SHA discovery immutable: remove prose claiming quick start resolves dev automatically; require a maintainer-approved SHA. - Make quick start rerunnable/safe: validate a clean working tree and reuse an existing bootstrap branch instead of failing. - Replace the incomplete 7/8-workflow, 5/17-runtime-resource inventory loop with the manifest-backed squad-install-verifier.mjs --verify-install check (8 workflows / 17 shared runtime resources). - Correct the least-privilege fallback lifecycle: bootstrap opens/ reuses a signed fallback issue, a human opens the Cast PR, and Squad Bootstrap must be manually re-dispatched to create the linked research-proposal issue; make this explicit in the quick-start outcome narrative. - Align the /squad implement and troubleshooting prose with the Profile A/B framing so it no longer recommends disabling PR creation while also claiming automatic implementation PRs. Sync the canonical enlistment guidance (.squad-templates/skills/gh-aw-enlistment/SKILL.md) and its 4 mirrors with the same Copilot-as-Bot GraphQL reviewer-request fix (verified via scripts/sync-templates.mjs --sync), and regenerate workflows/squad-workflows.manifest.json's enlistment-skill digest via squad-install-verifier.mjs --write-source. Update the two directly-related documentation contract tests: - test/gh-aw-enlistment-skill.test.ts: match the renamed Profile A heading used as a test slice boundary. - test/standalone-release-workflow.test.ts: assert the new requestReviewsByLogin/copilot-pull-request-reviewer approach instead of the removed --add-reviewer command. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

bradygaster requested a review from tamirdresher as a code owner October 2, 2026 19:00

Copilot AI balanced review requested due to automatic review settings October 2, 2026 19:00

Copilot started reviewing on behalf of bradygaster October 2, 2026 19:01

View session

Copilot AI reviewed Oct 2, 2026

View reviewed changes

bradygaster added the skip-changelog Skip changelog enforcement for this PR label Oct 2, 2026

bradygaster force-pushed the bradygaster-docs-gh-aw-setup-guide branch from ab28051 to e287566 Compare October 2, 2026 19:41

bradygaster merged commit 88b4550 into dev Oct 2, 2026
19 checks passed

bradygaster deleted the bradygaster-docs-gh-aw-setup-guide branch October 3, 2026 00:11

Navigation Menu

Repository navigation

docs(gh-aw): fix setup guide contradictions and sync enlistment guidance - #2153

docs(gh-aw): fix setup guide contradictions and sync enlistment guidance#2153
bradygaster merged 1 commit into
devfrom
bradygaster-docs-gh-aw-setup-guide

bradygaster commented Oct 2, 2026

Uh oh!

github-actions Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		expect(ghAwGuide).toContain('requestReviewsByLogin');
		expect(ghAwGuide).toContain('copilot-pull-request-reviewer');

Conversation

bradygaster commented Oct 2, 2026

What

Why

How

⚠️ Quick Check

PR Readiness Checklist

Branch & Commit

Build & Test

Changeset

Docs

Exports

Breaking Changes

Waivers

Uh oh!

github-actions Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 3 item(s) to address before review

Files Changed (9 files, +262 −60)

Uh oh!

github-actions Bot commented Oct 2, 2026

🟠 Impact Analysis — PR #2153

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 2, 2026 •

edited

Loading